Skip to main content
Version: 1.0.0

processCatalogOrderHttp

Process Catalog Order Template

Function Names: processCatalogOrderHttp / configure3DViewerHttp

Author: Domenico Cerone Creation Date: 25/09/2025
Last Reviewer: Domenico Cerone

Trigger: HTTPS (onRequest)

Purpose: Manages the cloning of products and variants to catalogs through two main functions: mass catalog order processing and individual 3D viewer configuration.

Detailed Functionality​

processCatalogOrderHttp - Mass Catalog Processing (Automatic)​

This is the main function that handles complete catalog order processing with automatic 3D viewer configuration. It performs the following workflow:

1. Order Validation and Status Management​

  • Receives orderId from the frontend via HTTP request
  • Retrieves the document from CatalogOrders collection using the provided ID
  • Sets order status to "processing_addition"
  • DUPLICATE CONTROL: Automatically identifies already processed assets (with cataloguesVariantsRef and cataloguesProductsRef) and marks them as "Failed - Duplicate"

2. Asset Processing and Grouping​

  • Filters only assets with isSelected=true and result="Available"
  • Groups remaining variants by productRef to avoid duplicates
  • STATUS TRACKING: Each asset in list_3d_assets_results receives a 'status' field:
    • "Complete" - Cloning was successful
    • "Failed - Duplicate" - Asset already in catalog or processing error

3. Database Operations with Resilience​

  • EXISTING VARIANTS CHECK: Before creating new variants, checks which ones are already present in the catalog via mainVariantRef
  • If product already added to catalog, adds only missing variants
  • Otherwise, creates new product in catalog
  • Clones only missing variants and associates them with the product
  • LASTUPDATE MANAGEMENT: Adds/updates lastUpdate field in "YYYY-MM-DD HH:MM:SS" format in all created/modified documents

4. Error Handling and Connectivity​

  • Extended timeout: 540 seconds (9 minutes) for long processing
  • Increased memory: 1GiB to handle large data volumes
  • Specific handling for connection errors (ECONNRESET, ENOTFOUND, ETIMEDOUT):
    • Automatic retry with incremental delay for failed operations
    • Delay between operations (50-100ms) to avoid database overload
    • Status code 503 for connection errors with retryable=true flag

5. Safe Restart Support​

  • Idempotency: Function can be called multiple times with same orderId without creating duplicates
  • Automatic Resume: If processing fails partially, restarting processes only missing elements
  • State Control: Already processed assets are automatically skipped
  • Detailed Logging: Clearly shows which elements are skipped and which are processed

6. catalogues_variants_map Creation​

  • Creates variant mapping arrays for each catalog product
  • Retrieves glassesName from CataloguesVariants for each variant
  • Updates existing mappings without creating duplicates
  • Maintains comprehensive product-variant relationships

7. Mass 3D Viewer Configuration (Automatic)​

  • AUTOMATIC EXECUTION: After cloning completion, automatically configures 3D viewer for all processed assets
  • Groups variants by product to optimize API calls
  • For each asset with status="Complete": calls internal configure3DViewer function
  • Automatically updates 3D URLs in CataloguesProducts and CataloguesVariants
  • Creates/updates 3DViewers structure with all products and variants
  • No manual intervention required - happens automatically as part of processCatalogOrderHttp

8. Notification Preference Check​

  • Customer Profile Check: Retrieves customer profile from Profiles collection using profile email
  • Notification Verification: Checks if processCatalogOrderHttp notification is enabled
  • Preference Field: Verifies notification_types.processCatalogOrderHttp field in the profile
  • Skip Condition: If notification is disabled (false): skips email sending entirely
  • Proceed Condition: If notification is enabled (true): continues with email notification system
  • Logging: Provides clear logging about notification preference status

9. Email Notification System​

  • Send Condition: Email sent ONLY if numberAssets > 0 (at least one successfully cloned asset)
  • Recipient Retrieval:
    • CatalogOrders[orderId] → 'profile' (customer profile ID)
    • Profiles[profile] → '_email' (customer email)
  • Customer Name Retrieval:
    • Profiles[profile] → 'firstName' + 'lastName' (customer full name)
    • If firstName/lastName missing, uses part before @ of email
  • Catalog Name Retrieval:
    • CatalogOrders[orderId] → 'catalogRef' (catalog ID)
    • Catalogues[catalogRef] → 'nameCatalog' (catalog name)
  • Asset Count: Counts only successfully cloned assets
  • Sending System: ZeptoMail with preconfigured template (MAIL_TEMPLATE_KEY: 13ef.8598f19fbcc5adb.k1.48ea6e70-5cb3-11f0-9e15-dad70ff08860.197eed3e6d7)
  • Template Data: numberAssets, nameCatalog, customer name

10. Notification Document Creation​

  • After email sending (if numberAssets > 0), automatically creates document in 'Notifications' collection
  • Document Structure: date, read (false), sentBy, sentTo, type, numberAssets, nameCatalog, catalogId
  • Error Handling: If document creation fails, logs error but doesn't interrupt process

configure3DViewerHttp - Individual 3D Viewer Configuration (Manual)​

This function configures the 3D viewer for individual catalog products when called manually or for specific cases. Unlike the automatic configuration in processCatalogOrderHttp, this is for targeted, individual configuration:

1. Catalog Reference Retrieval​

  • Retrieves CatalogOrder document using catalogOrderId
  • Extracts 'catalogRef' property from document

2. 3DViewers Management​

  • Searches '3DViewers' collection for document with 'catalog' = catalogRef
  • If exists: manages existing product in subcollection
  • If not exists: creates new 3DViewer with standard properties

3. Product and Variant Handling​

  • Existing Product: Adds catalogVariantId to 'list_variants' array (if not already present)
  • New Product: Creates new document with id, initialModel, and list_variants
  • Maintains proper product-variant relationships

4. 3D URL Updates​

  • Updates 'CataloguesProducts' with multiple3dViewerLink
  • Updates 'CataloguesVariants' with modelViewerUrl
  • URLs use actual 3DViewer document ID (not catalogOrderId)

5. URL Format​

  • Product URL: https://studio.arshades.it/Arshades3ds/{viewerId}/glasses/{catalogProductId}
  • Variant URL: https://studio.arshades.it/Arshades3d/{viewerId}/glasses/{catalogProductId}/variant/{catalogVariantId}

Technical Configuration​

  • Region: europe-central2
  • Timeout: 540 seconds (processCatalogOrderHttp), 60 seconds (configure3DViewerHttp)
  • Memory: 1GiB (processCatalogOrderHttp)
  • CORS: Enabled for frontend calls
  • Email Service: ZeptoMail with template system
  • Database: Firestore with optimized batch operations

Performance Optimization​

  • Batch Processing: Groups variants by product to reduce API calls
  • Connection Management: Axios with keep-alive and 30s timeout
  • Delay Management: Strategic delays to prevent database overload
  • Memory Efficiency: Optimized for handling large catalog orders
  • Streaming Updates: Real-time progress for long operations

Function Usage Scenarios​

Use processCatalogOrderHttp when:

  • Processing complete catalog orders with multiple products/variants
  • Need automatic 3D viewer configuration for all assets
  • Want email notifications sent to customers
  • Require bulk processing with batch optimization
  • Need comprehensive error handling and retry logic

Use configure3DViewerHttp when:

  • Configuring 3D viewer for individual products/variants
  • Need to fix specific 3D configuration issues
  • Testing 3D viewer setup for specific items
  • Manual intervention required for specific catalog entries
  • Debugging or troubleshooting individual 3D viewers

The system ensures complete catalog management with robust error handling, automatic recovery, and comprehensive tracking for enterprise-level operations.

Input (Payload):​

For processCatalogOrderHttp (Automatic Mass Processing):

{
  "orderId": "jbX3BOidkjMq15OYHlMC"
}

Note: This function automatically calls 3D viewer configuration for all processed assets at the end.

For configure3DViewerHttp (Manual Individual Configuration):

{
  "catalogOrderId": "xxx",
  "catalogProductId": "yyy",
  "catalogVariantId": "zzz"
}

Note: This function can be called independently to configure 3D viewer for individual products/variants when needed.

Output (Success):​

For processCatalogOrderHttp:

{
  "success": true,
  "message": "Processed 15 products for catalog",
  "results": [
    {
      "skuCode": "3102687C55110",
      "success": true,
      "result": {
        "newProductId": "catalog_product_id",
        "newVariantIds": ["catalog_variant_id"],
        "cataloguesVariantsRef": "catalog_variant_id",
        "cataloguesProductsRef": "catalog_product_id"
      }
    }
  ],
  "viewer3D": {
    "message": "3D viewer configuration: 12 successes, 3 failures on 8 products",
    "totalAssets": 15,
    "totalProducts": 8,
    "successful": 12,
    "failed": 3,
    "results": [
      {
        "skuCode": "3102687C55110",
        "success": true,
        "productId": "catalog_product_id",
        "variantId": "catalog_variant_id",
        "productUrl": "https://studio.arshades.it/Arshades3ds/viewer_id/glasses/product_id",
        "variantUrl": "https://studio.arshades.it/Arshades3d/viewer_id/glasses/product_id/variant/variant_id",
        "viewerId": "viewer_document_id"
      }
    ]
  },
  "emailNotification": {
    "success": true,
    "message": "Cloning completion notification email sent successfully",
    "recipient": "customer@email.com",
    "numberAssets": 12,
    "nameCatalog": "My Catalog",
    "customerName": "John Doe",
    "notificationId": "notification_doc_id"
  }
}

For configure3DViewerHttp:

{
  "success": true,
  "message": "3D viewer configuration completed successfully",
  "data": {
    "catalogOrderId": "xxx",
    "catalogRef": "catalog_ref_id",
    "catalogProductId": "yyy",
    "catalogVariantId": "zzz",
    "productUrl": "https://studio.arshades.it/Arshades3ds/viewer_id/glasses/yyy",
    "variantUrl": "https://studio.arshades.it/Arshades3d/viewer_id/glasses/yyy/variant/zzz",
    "viewerId": "3d_viewer_document_id"
  }
}

Testing​

URLs:

Test with Emulator:

  1. Start the Firebase emulator: firebase emulators:start --only functions
  2. Ensure you're using Node.js version 20: nvm use 20
  3. Test processCatalogOrderHttp with curl:
curl -X POST "http://127.0.0.1:5001/arshadesstaging/europe-central2/processCatalogOrderHttp" \
-H "Content-Type: application/json" \
-d '{"orderId": "jbX3BOidkjMq15OYHlMC"}'
  1. Test configure3DViewerHttp with curl:
curl -X POST "http://127.0.0.1:5001/arshadesstaging/europe-central2/configure3DViewerHttp" \
-H "Content-Type: application/json" \
-d '{"catalogOrderId": "xxx", "catalogProductId": "yyy", "catalogVariantId": "zzz"}'

Postman Testing:

For processCatalogOrderHttp:

For configure3DViewerHttp:

Deploy Commands:​

To deploy both functions:

firebase deploy --only functions:processCatalogOrderHttp,functions:configure3DViewerHttp

To deploy individual functions:

firebase deploy --only functions:processCatalogOrderHttp
firebase deploy --only functions:configure3DViewerHttp

Production URLs:​

processCatalogOrderHttp: https://europe-central2-arshades-7e18a.cloudfunctions.net/processCatalogOrderHttp

configure3DViewerHttp: https://europe-central2-arshades-7e18a.cloudfunctions.net/configure3DViewerHttp